HAL/LL drivers: security support

The purpose of this chapter is to details the security aspect based at the HAL and LL drivers based on

• ARMv8 architecture

• GTZC and RIF peripherals

RIF and GTZC HAL and LL drivers

The unification of RIF and Trust Zone APIs is critical due to their similar usage within application layers, requiring consistent and harmonized interfaces for common features across both GTZC and RIF drivers. To address this, the architecture enforces attribute management through dedicated functions designed to ensure code portability across HAL and LL drivers. These functions must independently manage security, privilege, and lock attributes, as well as read and write access operations, with clear separation between items and attributes within function parameters. Additionally, function implementations must support both static configurations—such as establishing security attributes during application initialization by isolating resources between secure and non-secure, privileged and non-privileged domains—and dynamic configurations that enable attribute reconfiguration based on evolving application needs. This approach ensures a flexible, robust, and unified framework for security attribute management.

The following table lists the HAL and LL RIF and GTZC naming rules:

Concept wording	HAL/LL RIF naming rule	HAL/LL GTZC naming rule
Block based sub-block	RISAB: Resource isolation slave unit for address space protection (block-based)	MPCBB: Memory Protection Controller Block-Based
Illegal access sub-block	IAC: Illegal access controller	TZIC: Trust Zone Illegal access Controller
Watermark sub-block	RISAF: Resource isolation slave unit for address space protection (full version)	TZSC_MPCWM: Memory Protection Controller - Watermark
Periph Attr sub-block	RIFSC: Resource Isolation Framework Security Controller RISC: Resource Isolation Slave Controller RIMC: Resource Isolation Master Controller	TZSC: Trust Zone Security Controller
Illegal access	ilac
Region	region	N/A
Sub Region	subregion
Security	Sec
Non-Secure	NSec
Privilege	Priv
Read	Rd
Write	Wr
Address	Addr
Public	Public	N/A
Non-Public	NPublic	N/A

RIF and GTZ HAL driver’s architecture

The HAL GTZ and RIF driver must follow the following giving the rules for the naming, enumerations, functions prototype, and return values:

• Enumerations:

  • Securable peripherals

    typedef enum
    {
      HAL_{RIF/GTZC}_{RISC/RIMC/TZSC}_TIM2  = LL_{RIF/GTZC}_TIM2,
      HAL_{RIF/GTZC}_{RISC/RIMC/TZSC}_UART4 = LL_{RIF/GTZC}_UART4,
      HAL_{RIF/GTZC}_{RISC/RIMC/TZSC}_ETH1  = LL_{RIF/GTZC}_{RIMC}_ETH1,
      ...
    } hal_{rif/gtzc}_{risc/rimc/tzsc}_periph_t;
    

  • Security attributes

    typedef enum
    {
      HAL_{RIF/GTZC}_NSEC = LL_{RIF/GTZC}_ATTR_NSEC,
      HAL_{RIF/GTZC}_SEC  = LL_{RIF/GTZC}_ATTR_SEC
    } hal_{rif/gtzc}_sec_attr_t;
    

  • Privilege attributes

    typedef enum
    {
      HAL_{RIF/GTZC}_NPRIV = LL_{RIF/GTZC}_ATTR_NPRIV,
      HAL_{RIF/GTZC}_PRIV  = LL_{RIF/GTZC}_ATTR_PRIV
    } hal_{rif/gtzc}_priv_attr_t;
    

  • Lock status

    typedef enum
    {
      HAL_{RIF/GTZC}_UNLOCKED = 0U,
      HAL_{RIF/GTZC}_LOCKED   = 1U
    } hal_{rif/gtzc}_lock_status_t;
    

• Functions:

  • Security and privilege attribute set/get functions

    hal_status_t HAL_{RIF/GTZC}_{RISC/RIMC/TZSC}_SetPeriph{AttrName}Attr(hal_{rif/gtzc}_{risc/rimc/tzsc}_periph_t periph,
                                                                         hal_{rif/gtzc}_{attrname}_attr_t attrname_attr);
    
    hal_{rif/gtzc}_{attrname}_attr_t HAL_{RIF/GTZC}_{RISC/RIMC/TZSC}_GetPeriph{AttrName}Attr(hal_{rif/gtzc}_{risc/rimc/tzsc}_periph_t periph);
    

  • Configuration lock functions

    hal_status_t HAL_{RIF/GTZC}_{RISC/RIMC/TZSC}_Lock{Periph}Config(void / hal_{rif/gtzc}_{risc/rimc/tzsc}_periph_t periph);
    
    hal_{rif/gtzc}_lock_status_t HAL_{RIF/GTZC}_{RISC/RIMC/TZSC}_IsLocked{Periph}Config(void / hal_{rif/gtzc}_{risc/rimc/tzsc}_periph_t periph);
    

Note

Depending on the hardware implementation, the scope of the configuration lock can be:

• Applied to the whole block. In this case, the lock functions above do not take parameters (void), and {Periph} is not included in the function names.

• Applied with finer granularity to lock the configuration for given peripheral(s). In this case, {Periph} is included in the function name, and a parameter specifies the peripheral to which the configuration lock applies.

• Examples

  typedef enum
  {
    HAL_RIF_RISC_TIM2  = LL_RIF_TIM2,
    HAL_RIF_RISC_UART4 = LL_RIF_UART4,
    ...
  } hal_rif_risc_periph_t;
  
  typedef enum
  {
    HAL_RIF_NSEC = LL_RIF_ATTR_NSEC,
    HAL_RIF_SEC  = LL_RIF_ATTR_SEC
  } hal_rif_sec_attr_t;
  
  typedef enum
  {
    HAL_RIF_UNLOCKED = 0U, /*!< RIF configuration unlocked */
    HAL_RIF_LOCKED   = 1U  /*!< RIF configuration locked   */
  } hal_rif_lock_status_t;
  
  hal_status_t HAL_RIF_RISC_SetPeriphSecAttr(hal_rif_risc_periph_t periph,
                                             hal_rif_sec_attr_t sec_attr);
  
  hal_rif_sec_attr_t HAL_RIF_RISC_GetPeriphSecAttr(hal_rif_risc_periph_t periph);
  
  hal_status_t HAL_RIF_RISC_LockPeriphConfig(hal_rif_risc_periph_t periph);
  
  hal_rif_lock_status_t HAL_RIF_RISC_IsLockedPeriphConfig(hal_rif_risc_periph_t periph);
  
  hal_status_t HAL_RIF_RIMC_LockConfig(void);
  hal_status_t HAL_RIF_RISC_LockConfig(void);
  
  hal_rif_lock_status_t HAL_RIF_RIMC_IsLockedConfig(void);
  hal_rif_lock_status_t HAL_RIF_RISC_IsLockedConfig(void);
  

  typedef enum
  {
    HAL_GTZC_TZSC_TIM2  = LL_GTZC_TIM2,
    HAL_GTZC_TZSC_UART4 = LL_GTZC_UART4,
    ...
  } hal_gtzc_tzsc_periph_t;
  
  typedef enum
  {
    HAL_GTZC_NSEC = LL_GTZC_ATTR_NSEC,
    HAL_GTZC_SEC  = LL_GTZC_ATTR_SEC
  } hal_gtzc_sec_attr_t;
  
  typedef enum
  {
    HAL_GTZC_UNLOCKED = 0x00U, /*!< GTZC configuration unlocked */
    HAL_GTZC_LOCKED   = 0x01U  /*!< GTZC configuration locked   */
  } hal_gtzc_lock_status_t;
  
  hal_status_t HAL_GTZC_TZSC_SetPeriphSecAttr(hal_gtzc_tzsc_periph_t periph,
                                              hal_gtzc_sec_attr_t sec_attr);
  
  hal_gtzc_sec_attr_t HAL_GTZC_TZSC_GetPeriphSecAttr(hal_gtzc_tzsc_periph_t periph);
  
  hal_status_t HAL_GTZC_TZSC_LockConfig(void);
  hal_gtzc_lock_status_t HAL_GTZC_IsLockedConfig(void);
  

Security and privilege attribute APIs for securable peripherals (RIF_RIFSC/GTZC_TZSC)

• Enumerations

  • Block-based memories

    typedef enum
    {
      HAL_{RIF/GTZC}_{RISAB/MPCBB}_{AXISRAM1/SRAM1} = LL_{RIF/GTZC}_{RISAB/MPCBB}_{AXISRAM1/SRAM1},
      HAL_{RIF/GTZC}_{RISAB/MPCBB}_{AXISRAM2/SRAM2} = LL_{RIF/GTZC}_{RISAB/MPCBB}_{AXISRAM2/SRAM2},
      HAL_{RIF/GTZC}_{RISAB/MPCBB}_{AXISRAM3/SRAM3} = LL_{RIF/GTZC}_{RISAB/MPCBB}_{AXISRAM3/SRAM3},
      ...
    } hal_{rif/gtzc}_{risab/mpcbb}_memory_t;
    

  • Secure-to-non-secure read/write access status

    typedef enum
    {
      HAL_{RIF/GTZC}_{RISAB/MPCBB}_SEC_TO_NSEC_DISABLED = 0x00U,
      HAL_{RIF/GTZC}_{RISAB/MPCBB}_SEC_TO_NSEC_ENABLED  = 0x01U
    } hal_{rif/gtzc}_{risab/mpcbb}_sec_to_nsec_access_status_t;
    

  • Memory clock security state (feature available on GTZC only)

    typedef enum
    {
      HAL_GTZC_MPCBB_CLK_SEC_NOT_INVERTED = LL_GTZC_MPCBB_CLK_SEC_NOT_INVERTED, /*!< GTZC clock security not inverted */
      HAL_GTZC_MPCBB_CLK_SEC_INVERTED     = LL_GTZC_MPCBB_CLK_SEC_INVERTED      /*!< GTZC clock security inverted     */
    } hal_gtzc_mpcbb_clk_sec_state_t;
    

  • Read/write access status (feature available on RIF peripheral only)

    typedef enum
    {
      HAL_RIF_{READ/WRITE}_DISABLED = LL_RIF_{READ/WRITE}_DISABLED,
      HAL_RIF_{READ/WRITE}_ENABLED  = LL_RIF_{READ/WRITE}_ENABLED
    } hal_rif_{read/write}_access_status_t;
    

  • RIF illegal access status (feature available on RIF peripheral only)

    typedef enum
    {
      HAL_RIF_ILAC_INACTIVE = 0x00U,
      HAL_RIF_ILAC_ACTIVE   = 0x01U
    } hal_rif_ilac_status_t;
    

    Note

    This enumeration is used to report the illegal access status for both RIF_RISAB and RISAF.

  • RIF illegal access read/write access

    typedef enum
    {
      HAL_RIF_ILAC_READ  = 0x00U,
      HAL_RIF_ILAC_WRITE = 0x01U
    } hal_rif_ilac_access_t;
    

• Structure

  • RIF illegal access memory information structure (not applicable for GTZC)

    typedef struct
    {
      hal_rif_ilac_access_t access;
      uint32_t              addr;
      hal_rif_sec_attr_t    sec;
      hal_rif_priv_attr_t   priv;
    } hal_rif_ilac_memory_info_t;
    

    Note

    The same structure is used for both RIF_RISAB and RIF_RISAF to provide illegal access information for a block-based memory or for the configuration of a watermark memory.

• Functions

  • Security and privilege attributes Set/Get functions

  hal_status_t HAL_{RIF/GTZC}_{RISAB/MPCBB}_Set{AttrName}Attr{ByBlock/ByAddr}(hal_{rif/gtzc}_{risab/mpcbb}_memory_t memory,
                                                                              uint32_t {start_block/offset_byte},
                                                                              uint32_t {block_nbr/size_byte},
                                                                              hal_{rif/gtzc}_{attrname}_attr_t attrname_attr);
  
  hal_{rif/gtzc}_{attrname}_attr_t HAL_{RIF/GTZC}_{RISAB/MPCBB}_Get{AttrName}Attr{ByBlock/ByAddr}(hal_{rif/gtzc}_{risab/mpcbb}_memory_t memory,
                                                                                                  uint32_t {block/offset_byte});
  

  Note

  The same hal_{rif/gtzc}_{attrname}_attr_t attribute enumeration described in the section Security and privilege attribute APIs for securable peripherals is used.

  • Enabling and disabling secure to non-secure read/write access

  hal_status_t HAL_{RIF/GTZC}_{RISAB/MPCBB}_EnableSecToNSecRdWrAccess(hal_{rif/gtzc}_{risab/mpcbb}_memory_t memory);
  
  hal_status_t HAL_{RIF/GTZC}_{RISAB/MPCBB}_DisableSecToNSecRdWrAccess(hal_{rif/gtzc}_{risab/mpcbb}_memory_t memory);
  
  hal_{rif/gtzc}_{risab/mpcbb}_sec_to_nsec_access_status_t HAL_{RIF/GTZC}_{RISAB/MPCBB}_IsEnabledSecToNSecRdWrAccess(hal_{rif/gtzc}_{risab/mpcbb}_memory_t memory);
  

  • Set/Get block based memory clock security state (feature available on GTZC only)

  hal_status_t HAL_GTZC_MPCBB_SetClkSecStateInvertion(hal_gtzc_mpcbb_memory_t memory_id,
                                                      hal_gtzc_mpcbb_clk_sec_state_t clk_sec_state);
  
  hal_gtzc_mpcbb_clk_sec_state_t HAL_GTZC_MPCBB_GetClkSecStateInvertion(hal_gtzc_mpcbb_memory_t memory);
  

  • Configuration lock

  hal_status_t HAL_{RIF/GTZC}_{RISAB/MPCBB}_LockConfig{ByPage/BySuperBlock/ByAddr}(hal_{rif/gtzc}_{risab/mpcbb}_memory_t memory,
                                                                                   uint32_t {start_page/start_super_blk/offset_byte},
                                                                                   uint32_t {page_nbr/super_blk_nbr/size_byte});
  
  hal_{rif/gtzc}_lock_status_t HAL_{RIF/GTZC}_{RISAB/MPCBB}_IsLockedConfig{ByPage/BySuperBlock/ByAddr}(hal_{rif/gtzc}_{risab/mpcbb}_memory_t memory,
                                                                                                       uint32_t {page/super_blk/offset_byte});
  

  Note

  The same hal_{rif/gtzc}_lock_status_t lock status enumeration described in the section Security and privilege attribute APIs for securable peripherals is used.

  • Enable and disable read/write access (feature available on RIF peripheral only)

    hal_status_t HAL_RIF_RISAB_{Enable/Disable}{Rd/Wr}Access{ByPage/ByAddr}(hal_rif_risab_memory_t memory,
                                                                            uint32_t {start_page/offset_byte},
                                                                            uint32_t {page_nbr/size_byte});
    
    hal_rif_{read/write}_access_status_t HAL_RIF_RISAB_IsEnabled{Page/Addr}{Rd/Wr}Access(hal_rif_risab_memory_t memory,
                                                                                         uint32_t {page/offset_byte});
    

  • Get illegal access info (feature available on RIF peripheral only)

    hal_rif_ilac_status_t HAL_RIF_RISAB_IsIllegalConfigAccess(hal_rif_risab_memory_t memory);
    hal_rif_ilac_status_t HAL_RIF_RISAB_IsIllegalMemoryAccess(hal_rif_risab_memory_t memory);
    
    void HAL_RIF_RISAB_GetIllegalMemoryAccessInfo(hal_rif_risab_memory_t memory,
                                                  hal_rif_ilac_memory_info_t *p_info);
    

• Examples

  typedef enum
  {
    HAL_RIF_RISAB_AXISRAM1 = LL_RIF_RISAB_AXISRAM1,
    HAL_RIF_RISAB_AXISRAM2 = LL_RIF_RISAB_AXISRAM2,
    ...
  } hal_rif_risab_memory_t;
  
  typedef enum
  {
    HAL_RIF_RISAB_SEC_TO_NSEC_DISABLED = 0x00U, /*!< RIF RISAB secure read/write data accesses to non-secure blocks and pages disabled */
    HAL_RIF_RISAB_SEC_TO_NSEC_ENABLED  = 0x01U  /*!< RIF RISAB secure read/write data accesses to non-secure blocks and pages enabled  */
  } hal_rif_risab_sec_to_nsec_access_status_t;
  

  hal_status_t HAL_RIF_RISAB_SetSecAttrByBlock(hal_rif_risab_memory_t memory,
                                               uint32_t start_block,
                                               uint32_t block_nbr,
                                               hal_rif_sec_attr_t sec_attr);
  
  hal_status_t HAL_RIF_RISAB_SetPrivAttrByBlock(hal_rif_risab_memory_t memory,
                                                uint32_t start_block,
                                                uint32_t block_nbr,
                                                hal_rif_priv_attr_t priv_attr);
  
  hal_rif_sec_attr_t HAL_RIF_RISAB_GetSecAttrByBlock(hal_rif_risab_memory_t memory,
                                                     uint32_t block);
  
  hal_rif_priv_attr_t HAL_RIF_RISAB_GetPrivAttrByBlock(hal_rif_risab_memory_t memory,
                                                       uint32_t block);
  
  hal_status_t HAL_RIF_RISAB_EnableSecToNSecRdWrAccess(hal_rif_risab_memory_t memory);
  hal_status_t HAL_RIF_RISAB_DisableSecToNSecRdWrAccess(hal_rif_risab_memory_t memory);
  
  hal_rif_risab_sec_to_nsec_access_status_t HAL_RIF_RISAB_IsEnabledSecToNSecRdWrAccess(hal_rif_risab_memory_t memory);
  
  hal_status_t HAL_RIF_RISAB_SetSecAttrByAddr(hal_rif_risab_memory_t memory,
                                              uint32_t offset_byte,
                                              uint32_t size_byte,
                                              hal_rif_sec_attr_t sec_attr);
  
  hal_status_t HAL_RIF_RISAB_SetPrivAttrByAddr(hal_rif_risab_memory_t memory,
                                               uint32_t offset_byte,
                                               uint32_t size_byte,
                                               hal_rif_priv_attr_t priv_attr);
  
  hal_rif_sec_attr_t HAL_RIF_RISAB_GetSecAttrByAddr(hal_rif_risab_memory_t memory,
                                                    uint32_t offset_byte);
  
  hal_rif_priv_attr_t HAL_RIF_RISAB_GetPrivAttrByAddr(hal_rif_risab_memory_t memory,
                                                      uint32_t offset_byte);
  
  hal_status_t HAL_RIF_RISAB_EnableRdAccessByPage(hal_rif_risab_memory_t memory,
                                                  uint32_t start_page,
                                                  uint32_t page_nbr);
  
  hal_status_t HAL_RIF_RISAB_DisableRdAccessByPage(hal_rif_risab_memory_t memory,
                                                   uint32_t start_page,
                                                   uint32_t page_nbr);
  
  hal_rif_read_access_status_t HAL_RIF_RISAB_IsEnabledPageRdAccess(hal_rif_risab_memory_t memory,
                                                                   uint32_t page);
  
  hal_status_t HAL_RIF_RISAB_EnableWrAccessByPage(hal_rif_risab_memory_t memory,
                                                  uint32_t start_page,
                                                  uint32_t page_nbr);
  
  hal_status_t HAL_RIF_RISAB_DisableWrAccessByPage(hal_rif_risab_memory_t memory,
                                                   uint32_t start_page,
                                                   uint32_t page_nbr);
  
  hal_rif_write_access_status_t HAL_RIF_RISAB_IsEnabledPageWrAccess(hal_rif_risab_memory_t memory,
                                                                    uint32_t page);
  
  hal_status_t HAL_RIF_RISAB_EnableRdAccessByAddr(hal_rif_risab_memory_t memory,
                                                  uint32_t offset_byte,
                                                  uint32_t size_byte);
  
  hal_status_t HAL_RIF_RISAB_DisableRdAccessByAddr(hal_rif_risab_memory_t memory,
                                                   uint32_t offset_byte,
                                                   uint32_t size_byte);
  
  hal_rif_read_access_status_t HAL_RIF_RISAB_IsEnabledAddrRdAccess(hal_rif_risab_memory_t memory,
                                                                   uint32_t offset_byte);
  
  hal_status_t HAL_RIF_RISAB_EnableWrAccessByAddr(hal_rif_risab_memory_t memory,
                                                  uint32_t offset_byte,
                                                  uint32_t size_byte);
  
  hal_status_t HAL_RIF_RISAB_DisableWrAccessByAddr(hal_rif_risab_memory_t memory,
                                                   uint32_t offset_byte,
                                                   uint32_t size_byte);
  
  hal_rif_write_access_status_t HAL_RIF_RISAB_IsEnabledAddrWrAccess(hal_rif_risab_memory_t memory,
                                                                    uint32_t offset_byte);
  

  typedef enum
  {
    HAL_GTZC_MPCBB_SRAM1 = (uint32_t)LL_GTZC_MPCBB_SRAM1, /*!< GTZC block based SRAM1 memory */
    HAL_GTZC_MPCBB_SRAM2 = (uint32_t)LL_GTZC_MPCBB_SRAM2, /*!< GTZC block based SRAM2 memory */
  #if defined(SRAM3_BASE)
    HAL_GTZC_MPCBB_SRAM3 = (uint32_t)LL_GTZC_MPCBB_SRAM3, /*!< GTZC block based SRAM3 memory */
  #endif /* SRAM3_BASE */
    HAL_GTZC_MPCBB_SRAM4 = (uint32_t)LL_GTZC_MPCBB_SRAM4, /*!< GTZC block based SRAM4 memory */
  #if defined(SRAM5_BASE)
    HAL_GTZC_MPCBB_SRAM5 = (uint32_t)LL_GTZC_MPCBB_SRAM5, /*!< GTZC block based SRAM5 memory */
  #endif /* SRAM5_BASE */
  #if defined(SRAM6_BASE)
    HAL_GTZC_MPCBB_SRAM6 = (uint32_t)LL_GTZC_MPCBB_SRAM6  /*!< GTZC block based SRAM6 memory */
  #endif /* SRAM6_BASE */
  } hal_gtzc_mpcbb_memory_t;
  
  typedef enum
  {
    HAL_GTZC_MPCBB_SEC_TO_NSEC_DISABLED = 0x00U,
    HAL_GTZC_MPCBB_SEC_TO_NSEC_ENABLED  = 0x01U
  } hal_gtzc_mpcbb_sec_to_nsec_access_status_t;
  
  typedef enum
  {
    HAL_GTZC_MPCBB_CLK_SEC_NOT_INVERTED = LL_GTZC_MPCBB_CLK_SEC_NOT_INVERTED, /*!< GTZC clock security not inverted */
    HAL_GTZC_MPCBB_CLK_SEC_INVERTED     = LL_GTZC_MPCBB_CLK_SEC_INVERTED      /*!< GTZC clock security inverted     */
  } hal_gtzc_mpcbb_clk_sec_state_t;
  

  hal_status_t HAL_GTZC_MPCBB_SetSecAttrByBlock(hal_gtzc_mpcbb_memory_t memory,
                                                uint32_t start_block,
                                                uint32_t block_nbr,
                                                hal_gtzc_sec_attr_t sec_attr);
  
  hal_status_t HAL_GTZC_MPCBB_SetPrivAttrByBlock(hal_gtzc_mpcbb_memory_t memory,
                                                 uint32_t start_block,
                                                 uint32_t block_nbr,
                                                 hal_gtzc_priv_attr_t priv_attr);
  
  hal_gtzc_sec_attr_t HAL_GTZC_MPCBB_GetSecAttrByBlock(hal_gtzc_mpcbb_memory_t memory,
                                                       uint32_t block);
  
  hal_gtzc_priv_attr_t HAL_GTZC_MPCBB_GetPrivAttrByBlock(hal_gtzc_mpcbb_memory_t memory,
                                                         uint32_t block);
  
  hal_status_t HAL_GTZC_MPCBB_EnableSecToNSecRdWrAccess(hal_gtzc_mpcbb_memory_t memory);
  
  hal_status_t HAL_GTZC_MPCBB_DisableSecToNSecRdWrAccess(hal_gtzc_mpcbb_memory_t memory);
  hal_gtzc_mpcbb_sec_to_nsec_access_status_t HAL_GTZC_MPCBB_IsEnabledSecToNSecRdWrAccess(hal_gtzc_mpcbb_memory_t memory);
  
  hal_status_t HAL_GTZC_MPCBB_SetClkSecStateInvertion(hal_gtzc_mpcbb_memory_t memory_id,
                                                      hal_gtzc_mpcbb_clk_sec_state_t clk_sec_state);
  
  hal_gtzc_mpcbb_clk_sec_state_t HAL_GTZC_MPCBB_GetClkSecStateInvertion(hal_gtzc_mpcbb_memory_t memory);
  
  hal_status_t HAL_GTZC_MPCBB_LockConfigBySuperBlock(hal_gtzc_mpcbb_memory_t memory,
                                                     uint32_t start_super_blk,
                                                     uint32_t super_blk_nbr);
  
  hal_gtzc_lock_status_t HAL_GTZC_MPCBB_IsLockedConfigBySuperBlock(hal_gtzc_mpcbb_memory_t memory,
                                                                   uint32_t super_blk);
  
  hal_status_t HAL_GTZC_MPCBB_SetSecAttrByAddr(hal_gtzc_mpcbb_memory_t memory,
                                               uint32_t offset_byte,
                                               uint32_t size_byte,
                                               hal_gtzc_sec_attr_t sec_attr);
  
  hal_status_t HAL_GTZC_MPCBB_SetPrivAttrByAddr(hal_gtzc_mpcbb_memory_t memory,
                                                uint32_t offset_byte,
                                                uint32_t size_byte,
                                                hal_gtzc_priv_attr_t priv_attr);
  
  hal_gtzc_sec_attr_t HAL_GTZC_MPCBB_GetSecAttrByAddr(hal_gtzc_mpcbb_memory_t memory,
                                                      uint32_t offset_byte);
  
  hal_gtzc_priv_attr_t HAL_GTZC_MPCBB_GetPrivAttrByAddr(hal_gtzc_mpcbb_memory_t memory,
                                                        uint32_t offset_byte);
  

Security and privilege attribute APIs for watermark memories (RIF_RISAF/ GTZC_TZSC-MPCWM)

Note

• On the RIF_RISAF peripheral, it is possible to define both regions and subregions. On GTZC_MPCWM, only subregions can be defined.

• Enabling and disabling read and write access is possible only on the RIF_RISAF peripheral and is configured by subregion.

• Locking the configuration is possible on both RIF_RISAF and GTZC_MPCWM and is configured by subregion.

• For generalization, both region-based and subregion-based variants of the APIs below must be provided for RIF. For GTZC, only the subregion-based API variant must be provided, and in this case there is no region parameter.

• Enumerations

  • RIF_RISAF/GTZC_TZSC-MPCWM memories

    typedef enum
    {
      HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_{XSPI1/OCTOSPI1} = LL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_{XSPI1/OCTOSPI1},
      HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_{XSPI2/OCTOSPI2} = LL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_{XSPI2/OCTOSPI2},
      ...
    } hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_memory_t;
    

  • RIF_RISAF regions (not applicable for GTZC)

    typedef enum
    {
      HAL_RIF_RISAF_REGION_1 = LL_RIF_RISAF_REGION_1, /*!< RIF RISAF region 1 */
      HAL_RIF_RISAF_REGION_2 = LL_RIF_RISAF_REGION_2, /*!< RIF RISAF region 2 */
      ...
    } hal_rif_risaf_region_t;
    

  • RIF_RISAF/GTZC_TZSC-MPCWM subregions

    typedef enum
    {
      HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_SUBREGION_A = LL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_SUBREGION_A,
      HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_SUBREGION_B = LL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_SUBREGION_B
    } hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_subregion_t;
    

  • RIF_RISAF/GTZC_TZSC-MPCWM Region and subregion enabled status

    typedef enum
    {
      HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_{REGION/SUBREGION}_DISABLED = 0U,
      HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_{REGION/SUBREGION}_ENABLED  = 1U
    } hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_{region/subregion}_status_t;
    

• Functions

  • Defining the region or the subregion: Set/get boundaries

    hal_status_t HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_Set{Region/SubRegion}Boundaries(hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_memory_t memory,
                                                                                   hal_rif_risaf_region_t region, /* applicable for RIF only */
                                                                                   hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_subregion_t subregion,
                                                                                   uint32_t offset_byte,
                                                                                   uint32_t size_byte);
    
    void HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_Get{Region/SubRegion}Boundaries(hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_memory_t memory,
                                                                           hal_rif_risaf_region_t region, /* applicable for RIF only */
                                                                           hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_subregion_t subregion,
                                                                           uint32_t *offset_byte,
                                                                           uint32_t *size_byte);
    

    Note

    For the RIF-RISAF peripheral, it is possible to define regions and subregions. On the GTZC-MPCWM, it is possible to define subregions only. Thus:

    • For RIF, both region and subregion variants of the APIs must be provided.

    • For GTZC, only the subregion variant of the API must be provided. In this GTZC case, there is no ‘region’ parameter (see also the next examples for RIF and GTZC).

  • Set/get attributes for a region/subregion

    hal_status_t HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_Set{Region/SubRegion}{AttrName}Attr(hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_memory_t memory,
                                                                                       hal_rif_risaf_region_t region, /* applicable for RIF only */
                                                                                       hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_subregion_t subregion,
                                                                                       hal_{rif/gtzc}_{attrname}_attr_t attrname_attr);
    
    hal_{rif/gtzc}_{attrname}_attr_t HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_Get{Region/SubRegion}{AttrName}Attr(hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_memory_t memory,
                                                                                                           hal_rif_risaf_region_t region, /* applicable for RIF only */
                                                                                                           hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_subregion_t subregion);
    

  • Enable and disable read/write access for a subregion

    Note

    Enabling and disabling read and write access is possible only on the RIF_RISAF peripheral and is configured by subregion. This feature is not available on GTZC_MPCWM.

    The same hal_rif_{read/write}_access_status_t enumeration used for RIF_RISAB is also used for RIF_RISAF to specify the read/write access status.

    hal_status_t HAL_RIF_RISAF_{Enable/Disable}SubRegion{Rd/Wr}Access(hal_rif_risaf_memory_t memory,
                                                                      hal_rif_risaf_region_t region,
                                                                      hal_rif_risaf_subregion_t subregion);
    
    hal_rif_{read/write}_access_status_t HAL_RIF_RISAF_IsEnabledSubRegion{Rd/Wr}Access(hal_rif_risaf_memory_t memory,
                                                                                       hal_rif_risaf_region_t region,
                                                                                       hal_rif_risaf_subregion_t subregion);
    

  • Enable and disable a region/subregion

  Note

  As described above, RIF supports both region-level and subregion-level configuration, so both API levels must be provided. GTZC supports only subregion-level configuration; therefore, only subregion APIs must be provided.

  hal_status_t HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_{Enable/Disable}{Region/SubRegion}(hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_memory_t memory,
                                                                                    hal_rif_risaf_region_t region,
                                                                                    hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_subregion_t subregion);
  
  hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_{region/subregion}_status_t HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_IsEnabled{Region/SubRegion}(hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_memory_t memory,
                                                                                                                              hal_rif_risaf_region_t region,
                                                                                                                              hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_subregion_t subregion);
  

  • Lock a subregion configuration

  Note

  Configuration locking is supported on both RIF-RISAF and GTZC-MPCWM, and can be applied independently to each subregion.

  hal_status_t HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_LockSubRegionConfig(hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_memory_t memory,
                                                                     hal_rif_risaf_region_t region,
                                                                     hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_subregion_t subregion);
  
  hal_{rif/gtzc}_lock_status_t HAL_{RIF/GTZC}_{RISAF/TZSC_MPCWM}_IsLockedSubRegionConfig(hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_memory_t memory,
                                                                                         hal_rif_risaf_region_t region,
                                                                                         hal_{rif/gtzc}_{risaf/tzsc_mpcwm}_subregion_t subregion);
  

  Note

  The same hal_{rif/gtzc}_lock_status_t lock status enumeration described in the section Security and privilege attribute APIs for securable peripherals is used to describe the lock status.

  • RIF_RISAF, illegal access, status and information functions (not possible on GTZC)

  hal_rif_ilac_status_t HAL_RIF_RISAF_IsIllegalConfigAccess(hal_rif_risaf_memory_t memory);
  hal_rif_ilac_status_t HAL_RIF_RISAF_IsIllegalMemoryAccess(hal_rif_risaf_memory_t memory);
  
  void HAL_RIF_RISAF_GetIllegalMemoryAccessInfo(hal_rif_risaf_memory_t memory,
                                                hal_rif_ilac_memory_info_t *p_info);
  

Note

The same hal_rif_ilac_status_t enumeration and hal_rif_ilac_memory_info_t structure described in the section Security and privilege attribute APIs for block-based memories (RIF_RISAB / GTZC_MPCBB) are used for both RIF_RISAB and RIF_RISAF.

• Examples

typedef enum
{
  HAL_RIF_RISAF_XSPI1  = LL_RIF_RISAF_XSPI1,
  HAL_RIF_RISAF_XSPI2  = LL_RIF_RISAF_XSPI2,
  HAL_RIF_RISAF_FMC    = LL_RIF_RISAF_FMC,
  HAL_RIF_RISAF_BKPRAM = LL_RIF_RISAF_BKPRAM
} hal_rif_risaf_memory_t;

typedef enum
{
  HAL_RIF_RISAF_REGION_1 = LL_RIF_RISAF_REGION_1,
  ..,
  HAL_RIF_RISAF_REGION_7 = LL_RIF_RISAF_REGION_7
} hal_rif_risaf_region_t;

typedef enum
{
  HAL_RIF_RISAF_SUBREGION_A = LL_RIF_RISAF_SUBREGION_A,
  HAL_RIF_RISAF_SUBREGION_B = LL_RIF_RISAF_SUBREGION_B
} hal_rif_risaf_subregion_t;

typedef enum
{
  HAL_RIF_RISAF_REGION_DISABLED = 0x00U,
  HAL_RIF_RISAF_REGION_ENABLED  = 0x01U
} hal_rif_risaf_region_status_t;

typedef enum
{
  HAL_RIF_RISAF_SUBREGION_DISABLED = 0x00U,
  HAL_RIF_RISAF_SUBREGION_ENABLED  = 0x01U
} hal_rif_risaf_subregion_status_t;

hal_status_t HAL_RIF_RISAF_SetRegionBoundaries(hal_rif_risaf_memory_t memory,
                                               hal_rif_risaf_region_t region,
                                               uint32_t offset_byte,
                                               uint32_t size_byte);

void HAL_RIF_RISAF_GetRegionBoundaries(hal_rif_risaf_memory_t memory,
                                       hal_rif_risaf_region_t region,
                                       uint32_t *offset_byte,
                                       uint32_t *size_byte);

hal_status_t HAL_RIF_RISAF_SetSubRegionBoundaries(hal_rif_risaf_memory_t memory,
                                                  hal_rif_risaf_region_t region,
                                                  hal_rif_risaf_subregion_t subregion,
                                                  uint32_t offset_byte,
                                                  uint32_t size_byte);

void HAL_RIF_RISAF_GetSubRegionBoundaries(hal_rif_risaf_memory_t memory,
                                          hal_rif_risaf_region_t region,
                                          hal_rif_risaf_subregion_t subregion,
                                          uint32_t *offset_byte,
                                          uint32_t *size_byte);

hal_status_t HAL_RIF_RISAF_SetRegionSecAttr(hal_rif_risaf_memory_t memory,
                                            hal_rif_risaf_region_t region,
                                            hal_rif_sec_attr_t sec_attr);

hal_status_t HAL_RIF_RISAF_SetRegionPrivAttr(hal_rif_risaf_memory_t memory,
                                             hal_rif_risaf_region_t region,
                                             hal_rif_priv_attr_t priv_attr);

hal_rif_sec_attr_t HAL_RIF_RISAF_GetRegionSecAttr(hal_rif_risaf_memory_t memory,
                                                  hal_rif_risaf_region_t region);

hal_rif_priv_attr_t HAL_RIF_RISAF_GetRegionPrivAttr(hal_rif_risaf_memory_t memory,
                                                    hal_rif_risaf_region_t region);

hal_status_t HAL_RIF_RISAF_SetSubRegionSecAttr(hal_rif_risaf_memory_t memory,
                                               hal_rif_risaf_region_t region,
                                               hal_rif_risaf_subregion_t subregion,
                                               hal_rif_sec_attr_t sec_attr);

hal_status_t HAL_RIF_RISAF_SetSubRegionPrivAttr(hal_rif_risaf_memory_t memory,
                                                hal_rif_risaf_region_t region,
                                                hal_rif_risaf_subregion_t subregion,
                                                hal_rif_priv_attr_t priv_attr);

hal_rif_sec_attr_t HAL_RIF_RISAF_GetSubRegionSecAttr(hal_rif_risaf_memory_t memory,
                                                     hal_rif_risaf_region_t region,
                                                     hal_rif_risaf_subregion_t subregion);

hal_rif_priv_attr_t HAL_RIF_RISAF_GetSubRegionPrivAttr(hal_rif_risaf_memory_t memory,
                                                       hal_rif_risaf_region_t region,
                                                       hal_rif_risaf_subregion_t subregion);

hal_status_t HAL_RIF_RISAF_EnableSubRegionWrAccess(hal_rif_risaf_memory_t memory,
                                                   hal_rif_risaf_region_t region,
                                                   hal_rif_risaf_subregion_t subregion);

hal_status_t HAL_RIF_RISAF_DisableSubRegionWrAccess(hal_rif_risaf_memory_t memory,
                                                    hal_rif_risaf_region_t region,
                                                    hal_rif_risaf_subregion_t subregion);

hal_status_t HAL_RIF_RISAF_EnableSubRegionRdAccess(hal_rif_risaf_memory_t memory,
                                                   hal_rif_risaf_region_t region,
                                                   hal_rif_risaf_subregion_t subregion);

hal_status_t HAL_RIF_RISAF_DisableSubRegionRdAccess(hal_rif_risaf_memory_t memory,
                                                    hal_rif_risaf_region_t region,
                                                    hal_rif_risaf_subregion_t subregion);

hal_rif_write_access_status_t HAL_RIF_RISAF_IsEnabledWrAccessSubRegion(hal_rif_risaf_memory_t memory,
                                                                       hal_rif_risaf_region_t region,
                                                                       hal_rif_risaf_subregion_t subregion);

hal_rif_read_access_status_t HAL_RIF_RISAF_IsEnabledRdAccessSubRegion(hal_rif_risaf_memory_t memory,
                                                                      hal_rif_risaf_region_t region,
                                                                      hal_rif_risaf_subregion_t subregion);

hal_status_t HAL_RIF_RISAF_EnableRegion(hal_rif_risaf_memory_t memory,
                                        hal_rif_risaf_region_t region);

hal_status_t HAL_RIF_RISAF_DisableRegion(hal_rif_risaf_memory_t memory,
                                         hal_rif_risaf_region_t region);

hal_rif_risaf_region_status_t HAL_RIF_RISAF_IsEnabledRegion(hal_rif_risaf_memory_t memory,
                                                            hal_rif_risaf_region_t region);

hal_status_t HAL_RIF_RISAF_EnableSubRegion(hal_rif_risaf_memory_t memory,
                                           hal_rif_risaf_region_t region,
                                           hal_rif_risaf_subregion_t subregion);

hal_status_t HAL_RIF_RISAF_DisableSubRegion(hal_rif_risaf_memory_t memory,
                                            hal_rif_risaf_region_t region,
                                            hal_rif_risaf_subregion_t subregion);

hal_rif_risaf_subregion_status_t HAL_RIF_RISAF_IsEnabledSubRegion(hal_rif_risaf_memory_t memory,
                                                                  hal_rif_risaf_region_t region,
                                                                  hal_rif_risaf_subregion_t subregion);

hal_status_t HAL_RIF_RISAF_LockSubRegionConfig(hal_rif_risaf_memory_t memory,
                                               hal_rif_risaf_region_t region,
                                               hal_rif_risaf_subregion_t subregion);

hal_rif_lock_status_t HAL_RIF_RISAF_IsLockedSubRegionConfig(hal_rif_risaf_memory_t memory,
                                                            hal_rif_risaf_region_t region,
                                                            hal_rif_risaf_subregion_t subregion);

hal_rif_ilac_status_t HAL_RIF_RISAF_IsIllegalConfigAccess(hal_rif_risaf_memory_t memory);

hal_rif_ilac_status_t HAL_RIF_RISAF_IsIllegalMemoryAccess(hal_rif_risaf_memory_t memory);

void HAL_RIF_RISAF_GetIllegalMemoryAccessInfo(hal_rif_risaf_memory_t memory,
                                              hal_rif_ilac_memory_info_t *p_info);

typedef enum
{
  HAL_GTZC_TZSC_MPCWM_XSPI1 = LL_GTZC_TZSC_MPCWM_XSPI1,
  HAL_GTZC_TZSC_MPCWM_XSPI2 = LL_GTZC_TZSC_MPCWM_XSPI2,
  ...
} hal_gtzc_tzsc_mpcwm_memory_t;

typedef enum
{
  HAL_GTZC_TZSC_MPCWM_SUBREGION_A = LL_GTZC_TZSC_MPCWM_SUBREGION_A,
  HAL_GTZC_TZSC_MPCWM_SUBREGION_B = LL_GTZC_TZSC_MPCWM_SUBREGION_B
} hal_gtzc_tzsc_mpcwm_subregion_t;

typedef enum
{
  HAL_GTZC_TZSC_MPCWM_SUBREGION_DISABLED = 0x00U,
  HAL_GTZC_TZSC_MPCWM_SUBREGION_ENABLED  = 0x01U
} hal_gtzc_tzsc_mpcwm_subregion_status_t;

hal_status_t HAL_GTZC_TZSC_MPCWM_SetSubRegionBoundaries(hal_gtzc_tzsc_mpcwm_memory_t memory,
                                                        hal_gtzc_tzsc_mpcwm_subregion_t subregion,
                                                        uint32_t offset_byte,
                                                        uint32_t size_byte);

void HAL_GTZC_TZSC_MPCWM_GetSubRegionBoundaries(hal_gtzc_tzsc_mpcwm_memory_t memory,
                                                hal_gtzc_tzsc_mpcwm_subregion_t subregion,
                                                uint32_t *offset_byte,
                                                uint32_t *size_byte);

hal_status_t HAL_GTZC_TZSC_MPCWM_SetSubRegionSecAttr(hal_gtzc_tzsc_mpcwm_memory_t memory,
                                                     hal_gtzc_tzsc_mpcwm_subregion_t subregion,
                                                     hal_gtzc_sec_attr_t sec_attr);

hal_gtzc_sec_attr_t HAL_GTZC_TZSC_MPCWM_GetSubRegionSecAttr(hal_gtzc_tzsc_mpcwm_memory_t memory,
                                                            hal_gtzc_tzsc_mpcwm_subregion_t subregion);

hal_status_t HAL_GTZC_TZSC_MPCWM_SetSubRegionPrivAttr(hal_gtzc_tzsc_mpcwm_memory_t memory,
                                                      hal_gtzc_tzsc_mpcwm_subregion_t subregion,
                                                      hal_gtzc_priv_attr_t priv_attr);

hal_gtzc_priv_attr_t HAL_GTZC_TZSC_MPCWM_GetSubRegionPrivAttr(hal_gtzc_tzsc_mpcwm_memory_t memory,
                                                              hal_gtzc_tzsc_mpcwm_subregion_t subregion);

hal_status_t HAL_GTZC_TZSC_MPCWM_EnableSubRegion(hal_gtzc_tzsc_mpcwm_memory_t memory,
                                                 hal_gtzc_tzsc_mpcwm_subregion_t subregion);

hal_status_t HAL_GTZC_TZSC_MPCWM_DisableSubRegion(hal_gtzc_tzsc_mpcwm_memory_t memory,
                                                  hal_gtzc_tzsc_mpcwm_subregion_t subregion);

hal_gtzc_tzsc_mpcwm_subregion_status_t HAL_GTZC_TZSC_MPCWM_IsEnabledSubRegion(hal_gtzc_tzsc_mpcwm_memory_t memory,
                                                                              hal_gtzc_tzsc_mpcwm_subregion_t subregion);

Illegal access

The illegal access detection feature applies upon any security illegal access: i.e for RIF/GTZC aware peripherals, securable peripherals, Block based and watermark.

• Enumerations

  • Illegal access peripherals

    typedef enum
    {
      HAL_{RIF/GTZC}_{IAC/TZIC}_TIM2  = LL_{RIF/GTZC}_TIM2,
      HAL_{RIF/GTZC}_{IAC/TZIC}_UART4 = LL_{RIF/GTZC}_UART4,
      HAL_{RIF/GTZC}_{IAC/TZIC}_ETH1  = LL_{RIF/GTZC}_{RIMC}_ETH1,
      ...
    } hal_{rif/gtzc}_{iac/tzic}_periph_t;
    

  • Illegal access interrupt status

    typedef enum
    {
      HAL_{RIF/GTZC}_{IAC/TZIC}_IT_DISABLED = 0U,
      HAL_{RIF/GTZC}_{IAC/TZIC}_IT_ENABLED  = 1U
    } hal_{rif/gtzc}_{iac/tzic}_it_status_t;
    

• Functions

  • Illegal access interrupt management functions (enable/disable, IRQ handler, and callback)

    void HAL_{RIF/GTZC}_{IAC/TZIC}_EnableIT(hal_{rif/gtzc}_{iac/tzic}_periph_t periph);
    
    void HAL_{RIF/GTZC}_{IAC/TZIC}_DisableIT(hal_{rif/gtzc}_{iac/tzic}_periph_t periph);
    
    hal_{rif/gtzc}_{iac/tzic}_it_status_t HAL_{RIF/GTZC}_{IAC/TZIC}_IsEnabledIT(hal_{rif/gtzc}_{iac/tzic}_periph_t periph);
    
    void HAL_{RIF/GTZC}_{IAC/TZIC}_IRQHandler(void);
    
    void HAL_{RIF/GTZC}_{IAC/TZIC}_Callback(hal_{rif/gtzc}_{iac/tzic}_periph_t periph);
    

• Examples

typedef enum
{
  HAL_RIF_IAC_TIM2 = LL_RIF_TIM2,
  ...
} hal_rif_iac_periph_t;

typedef enum
{
  HAL_RIF_IAC_IT_DISABLED = 0U,
  HAL_RIF_IAC_IT_ENABLED  = 1U
} hal_rif_iac_it_status_t;

hal_status_t HAL_RIF_IAC_EnableIT(hal_rif_iac_periph_t periph);
hal_status_t HAL_RIF_IAC_DisableIT(hal_rif_iac_periph_t periph);
hal_rif_iac_it_status_t HAL_RIF_IAC_IsEnabledIT(hal_rif_iac_periph_t periph);

void HAL_RIF_IAC_IRQHandler(void);
void HAL_RIF_IAC_Callback(hal_rif_iac_periph_t periph);

typedef enum
{
  HAL_GTZC_TZIC_TIM2  = LL_GTZC_TIM2,
  ...
} hal_gtzc_tzic_periph_t;

typedef enum
{
  HAL_GTZC_TZIC_IT_DISABLED = 0U,
  HAL_GTZC_TZIC_IT_ENABLED  = 1U
} hal_gtzc_tzic_it_status_t;

hal_status_t HAL_GTZC_TZIC_EnableIT(hal_gtzc_tzic_periph_t periph);
hal_status_t HAL_GTZC_TZIC_DisableIT(hal_gtzc_tzic_periph_t periph);
hal_gtzc_tzic_it_status_t HAL_GTZC_TZIC_IsEnabledIT(hal_gtzc_tzic_periph_t periph);

void HAL_GTZC_TZIC_IRQHandler(void);
void HAL_GTZC_TZIC_Callback(hal_gtzc_tzic_periph_t periph);

HAL and LL RIF-aware/TZ-aware peripherals APIs

The HAL and LL layers must include TrustZone (TZ)-aware and RIF-aware PPP attribute management functions, with each TZ-aware/RIF-aware PPP LL HAL and LL module providing its own attribute management APIs. Attribute management must be provided as standalone. The RIF-aware/TZ-aware HAL PPP attribute APIs must be callable independently of the HAL PPP handle initialization, with the HAL PPP instance as the first parameter replacing the traditional handle parameter. See also paragraph HAL PPP instance retrieving to understand how to get the PPP peripheral instance from the HAL PPP handle.

Attribute functions must be unified across TZ-aware modules and families, and when possible, between RIF and TZ implementations.

Items (such as PVD and WKUPPIN) must be clearly separated from their attributes (Secure/NSecure).

Except the attribute setting functions, No other HAL nor LL function within any module must impact the configured TZ/RIF attributes, ensuring system integrity. Function usage must support both static configurations aligned with Trusted Execution Environment requirements (also called isolation) and dynamic reconfiguration to adjust attributes according to application needs.

In the application code, when the RIF-aware/TZ-aware HAL/LL PPP attribute functions are called statically (i.e. from the isolation part) then it must use directly the needed instance.

// Using LL driver
LL_PPP_Func(PPPn, ...);

// Using HAL driver
HAL_PPP_Func(HAL_PPPn, ...);

When these functions are called dynamically (to reconfigure/adjust the attributes according to the application needs), the application must use the appropriate function to retrieve the instance from the handle (if the given driver uses a handle) and use it to call the attribute function.

// Using LL driver
LL_PPP_Func(HAL_PPP_GetLLInstance(hppp), ...);

// Using HAL driver
HAL_PPP_Func(HAL_PPP_GetInstance(hppp), ...);

LL RIF-aware/TZ-aware peripherals APIs

• Attribute management functions

  __STATIC_INLINE void LL_{PPP}_{SUBBLOCK}_Set{AttrName}Attr({PPP_TypeDef *pppx},
                                                             {uint32_t item/subinstance},
                                                             uint32_t {attrname}_attr);
  
  __STATIC_INLINE uint32_t LL_{PPP}_{SUBBLOCK}_Get{AttrName}Attr({PPP_TypeDef *pppx},
                                                                 {uint32_t item/subinstance});
  __STATIC_INLINE void LL_{PPP}_{SUBBLOCK}_Lock{AttrName}Attr({PPP_TypeDef *pppx},
                                                              {uint32_t items/subinstances});
  
  __STATIC_INLINE void LL_{PPP}_{SUBBLOCK}_Unlock{AttrName}Attr({PPP_TypeDef *pppx},
                                                                {uint32_t items/subinstances});
  
  __STATIC_INLINE uint32_t LL_{PPP}_{SUBBLOCK}_IsLocked{AttrName}Attr({PPP_TypeDef *pppx},
                                                                      {uint32_t item/subinstance});
  

With:

• The {PPP} is the name of the peripheral.

• The {SUBBLOCK} (when existing) within a TZ-aware/RIF-aware LL module must be applied to the set/get attribute APIs.

• The {AttrName} is the attribute abbreviation described here: - Sec, Priv, Public

pppx is: - The physical instance of type PPP_TypeDef* when existing in the given driver (e.g. LL FLASH).

• Omitted when the given HAL driver does not use an instance, like the LL RCC or PWR.

• Items/subinstances:

  • Use subinstances when the attribute applies to sub‑instances meaning multiple identical resources of the same peripherals (e.g. pins in case of the GPIO). In this case these APIs reuse the already existing subinstances naming and definitions (e.g. in case of GPIO, subinstances = pins and must be set to the defines LL_GPIO_PIN_n).

  • Use items when the attribute applies to heterogeneous/specific parts of the given peripheral instance (e.g. the RCC oscillators and PLLs and other items). In this case a set of dedicated defines is provided to list these items with the following naming rules LL_{PPP}_{ATTRNAME}_ITEM_{ITEM}, LL_{PPP}_{ATTRNAME}_ITEM_ALL being required.

  • Omitted when the attributes setting or lock apply to the given PPP instance. In this case only the pppx instance is used if the LL driver already uses it, if not the function becomes void.

Note

• Set attributes APIs can be applied for one or several items/subinstances (defines can be ORed/combined when possible).

• Get attributes APIs must be applied for one single item/subinstance (cannot be ORed/combined).

• Lock/Unlock/IsLocked APIs parameters (instance, items/subinstances) must be aligned with:

  • the given LL driver: whether it uses a PPP_TypeDef instance or not (case of the RCC),

  • the given device capability (whether the lock can be performed at instance granularity or at item/sub‑instance granularity).

• The unlock function must be provided only if it is possible to unlock on the fly (i.e. without the need of a system reset).

• The IsLocked API must return the numerical value 1 when locked and 0 when unlocked (same as all other LL_PPP_Isxxx APIs).

• Examples

  • RCC

  #define LL_RCC_ATTR_NSEC              0UL
  #define LL_RCC_ATTR_SEC               1UL
  
  #define LL_RCC_ATTR_NPRIV             0UL
  #define LL_RCC_ATTR_PRIV              1UL
  
  #define LL_RCC_ATTR_NPUBLIC           0UL
  #define LL_RCC_ATTR_PUBLIC            1UL
  
  #define LL_RCC_SEC_ITEM_HSE           RCC_SECCFGR_HSE
  ...
  #define LL_RCC_SEC_ITEM_PERIPHCLK     RCC_SECCFGR_PER
  #define LL_RCC_SEC_ITEM_ALL           RCC_SECURE_MASK
  
  #define LL_RCC_PRIV_ITEM_SYSCLK       RCC_PRIVCFGR_SYS
  ...
  #define LL_RCC_PRIV_ITEM_PERIPHCLK    RCC_PRIVFGR_PERIPH
  #define LL_RCC_PRIV_ITEM_ALL          RCC_PRIVRE_MASK
  
  #define LL_RCC_LOCK_ITEM_RESET_FLAGS  RCC_RCFGLOCKR_RMVF
  ...
  #define LL_RCC_LOCK_ITEM_PERIPHCLK    RCC_RCFGLOCKR_PERIPH
  #define LL_RCC_LOCK_ITEM_ALL          RCC_PRIVRE_MASK
  

  __STATIC_INLINE void     LL_RCC_SetSecAttr(uint32_t item, uint32_t sec_attr);
  __STATIC_INLINE uint32_t LL_RCC_GetSecAttr(uint32_t item);
  
  __STATIC_INLINE void     LL_RCC_SetPrivAttr(uint32_t item, uint32_t priv_attr);
  __STATIC_INLINE uint32_t LL_RCC_GetPrivAttr(uint32_t item);
  
  __STATIC_INLINE void     LL_RCC_LockAttr(uint32_t item);
  __STATIC_INLINE uint32_t LL_RCC_IsLockedAttr(uint32_t item);
  

Note

In this LL RCC example:

• The instance is omitted as it is not used in the LL RCC driver.

• Items are used, as the attribute setting applies to heterogeneous (non-identical) parts of the RCC such as HSE, LSE, etc.

• Locking is possible per item in this example.

• No unlock API is provided, as unlock is not possible (unlock is performed by a system reset).

• GPIO

#define LL_GPIO_PIN_0          GPIO_BSRR_BS0      /*!< Select pin 0  */
#define LL_GPIO_PIN_1          GPIO_BSRR_BS1      /*!< Select pin 1  */
...
#define LL_GPIO_PIN_14         GPIO_BSRR_BS14     /*!< Select pin 14 */
#define LL_GPIO_PIN_15         GPIO_BSRR_BS15     /*!< Select pin 15 */
#define LL_GPIO_PIN_ALL

#define LL_GPIO_ATTR_NSEC      0U                 /*!< I/O pin is non-secure    */
#define LL_GPIO_ATTR_SEC       GPIO_SECCFGR_SEC0  /*!< I/O pin is secure        */

#define LL_GPIO_ATTR_NPRIV     0U                 /*!< I/O pin is unprivileged  */
#define LL_GPIO_ATTR_PRIV      GPIO_PRIVCFGR_PRIV0 /*!< I/O pin is privileged   */

__STATIC_INLINE void LL_GPIO_SetSecAttr(GPIO_TypeDef *gpiox,
                                        uint32_t pin_mask,
                                        uint32_t sec_attr);

__STATIC_INLINE uint32_t LL_GPIO_GetSecAttr(const GPIO_TypeDef *gpiox,
                                            uint32_t pin);

__STATIC_INLINE void LL_GPIO_SetPrivAttr(GPIO_TypeDef *gpiox,
                                         uint32_t pin_mask,
                                         uint32_t priv_attr);

__STATIC_INLINE uint32_t LL_GPIO_GetPrivAttr(const GPIO_TypeDef *gpiox,
                                             uint32_t pin);

__STATIC_INLINE void LL_GPIO_LockAttr(GPIO_TypeDef *gpiox, uint32_t pin_mask);
__STATIC_INLINE uint32_t LL_GPIO_IsLockedAttr(const GPIO_TypeDef *gpiox, uint32_t pin);

Note

In this LL GPIO example:

• The GPIO_TypeDef instance is used and corresponds to the GPIO port.

• The subinstances are the pins, using the same LL_GPIO_PIN_n defines as the overall driver.

• The attributes lock can be done by pin(s) in the above example.

• The attributes IsLocked API return the numerical values “0” or “1”.

• EXTI

#define LL_EXTI_LINE_0          EXTI_IMR1_IM0      /*!< Extended line 0  */
...
#define LL_EXTI_LINE_31         EXTI_IMR1_IM31     /*!< Extended line 31 */
#define LL_EXTI_LINE_ALL_0_31   EXTI_IMR1_IM_ALL   /*!< All extended lines from 0 to 31 */

#define LL_EXTI_LINE_32         EXTI_IMR2_IM32     /*!< Extended line 32 */
...
#define LL_EXTI_LINE_63         EXTI_IMR2_IM63     /*!< Extended line 63 */
#define LL_EXTI_LINE_ALL_32_63  EXTI_IMR2_IM_ALL   /*!< All extended lines from 32 to 63 */

#define LL_EXTI_ATTR_NSEC       0U
#define LL_EXTI_ATTR_SEC        1U

#define LL_EXTI_ATTR_NPRIV      0U
#define LL_EXTI_ATTR_PRIV       1U

/**
  * @param  exti_line This parameter can be a combination of the following values:
  *         @arg @ref LL_EXTI_LINE_0
  *         @arg @ref LL_EXTI_LINE_1
  *         ...
  *         @arg @ref LL_EXTI_LINE_31
  */
__STATIC_INLINE void LL_EXTI_SetSecAttr_0_31(uint32_t exti_line, uint32_t sec_attr);

/**
  * @param  exti_line This parameter can be one of the following values:
  *         @arg @ref LL_EXTI_LINE_0
  *         @arg @ref LL_EXTI_LINE_1
  *         ...
  *         @arg @ref LL_EXTI_LINE_31
  */
__STATIC_INLINE uint32_t LL_EXTI_GetSecAttr_0_31(uint32_t exti_line);

/**
  * @param  exti_line This parameter can be a combination of the following values:
  *         @arg @ref LL_EXTI_LINE_32
  *         @arg @ref LL_EXTI_LINE_33
  *         ...
  *         @arg @ref LL_EXTI_LINE_63
  */
__STATIC_INLINE void LL_EXTI_SetSecAttr_32_63(uint32_t exti_line, uint32_t sec_attr);

/**
  * @param  exti_line This parameter can be one of the following values:
  *         @arg @ref LL_EXTI_LINE_32
  *         @arg @ref LL_EXTI_LINE_33
  *         ...
  *         @arg @ref LL_EXTI_LINE_63
  */
__STATIC_INLINE uint32_t LL_EXTI_GetSecAttr_32_63(uint32_t exti_line);

/* Same pattern for SetPrivAttr/GetPrivAttr APIs */

__STATIC_INLINE void LL_EXTI_LockAttr(void);
__STATIC_INLINE uint32_t LL_EXTI_IsLockedAttr(void); /* Returns numerical values 0 or 1 */

Note

In this LL EXTI example:

• The instance is omitted, as the LL EXTI driver does not use an EXTI_TypeDef instance.

• The subinstances are the EXTI lines, using the same LL_EXTI_LINE_n defines as the rest of the LL EXTI driver.

• The line defines can be combined (ORed) for the Set APIs, but not for the Get APIs.

• The LockAttr and IsLockedAttr functions take no parameter in this example, as the hardware allows locking all line attributes together.

• The IsLockedAttr API returns the numerical values 0 or 1.

• NVM

#define LL_NVM_ATTR_NSEC     0UL
#define LL_NVM_ATTR_SEC      1UL

#define LL_NVM_ATTR_NPRIV    0UL
#define LL_NVM_ATTR_PRIV     1UL

#define LL_NVM_SEC_ITEM_PM      NVM_SECCFGR_PM
#define LL_NVM_SEC_ITEM_PERF    NVM_SECCFGR_PERF
..
#define LL_NVM_SEC_ITEM_ALL     ..

#define LL_NVM_PRIV_ITEM_PM     NVM_PRIVCFGR_PM
..
#define LL_NVM_PRIV_ITEM_ALL    ..

#define LL_NVM_LOCK_ITEM_PM     NVM_RCFGLOCKR_PM
..
#define LL_NVM_LOCK_ITEM_ALL    ..

__STATIC_INLINE void LL_NVM_SetSecAttr(NVM_TypeDef *nvmx,
                                       uint32_t item,
                                       uint32_t sec_attr);

__STATIC_INLINE uint32_t LL_NVM_GetSecAttr(const NVM_TypeDef *nvmx,
                                           uint32_t item);

__STATIC_INLINE void LL_NVM_SetPrivAttr(NVM_TypeDef *nvmx,
                                        uint32_t item,
                                        uint32_t priv_attr);

__STATIC_INLINE uint32_t LL_NVM_GetPrivAttr(const NVM_TypeDef *nvmx,
                                            uint32_t item);

__STATIC_INLINE void LL_NVM_LockAttr(NVM_TypeDef *nvmx,
                                     uint32_t item);

__STATIC_INLINE uint32_t LL_NVM_IsLockedAttr(const NVM_TypeDef *nvmx,
                                             uint32_t item);

Note

In this LL NVM example, the attributes APIs use:

• The existing instance of type NVM_TypeDef

• items as the attributes setting applies to heterogenous parts (not identical) of the NVM.

The items can be combined for the Set and Lock APIs. Not for the Get / IsLocked APIs.. - The IsLocked API returns the numeric values 0 or 1.

HAL RIF-aware/TZ-aware peripherals APIs

Security compile-time conditional checks

Privilege compile-time conditional checks